home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / c / lib_dos.exe / WI.DOC < prev    next >
Text File  |  1991-05-26  |  25KB  |  647 lines
  1. -------------------------[ WI.LIB ]----------for DOS---------------------------
  2.                       WI.LIB - Wilkes Index Library
  3.                     Copyright (c) 1989 by Roger Wilkes
  4.            Member: Association of Shareware Professionals (ASP)
  5.                   Cost of this Software $40; Gov./Ed. $30
  6.                         Wilkes Software, inc.
  7.                         Memphis, TN 38134
  8.                     or Register on BBS at (901)377-5608
  9. -------------------------------------------------------------------------------
  10.  
  11.     There are a total of six (6) function calls available with this library.
  12. 1) IX_add        - to add keys to an index file
  13. 2) IX_del        - to delete keys from an index file
  14. 3) IX_find_first - to find the first key which meets comparison criteria
  15. 4) IX_find_last  - to find the last key which meets comparison criteria
  16. 5) IX_find_next  - to find the next key
  17. 6) IX_find_prev  - to find the previous key
  18.  
  19. -------------------------------------------------------------------------------
  20.  
  21.     You must insure that "WI.LIB" is available to the linker at link time.
  22. WI.LIB is to be linked with Microsoft large (-AL) and huge (-AH) memory
  23. models.
  24.  
  25.     Place WI.LIB in your LIB directory and place INDEX.H in your INCLUDE
  26. directory.
  27.  
  28.     The maximum char array key length is 127.  All data types other than this
  29. one can use the "data_type" defines (see INDEX.H).  The character array
  30. data type is formed by anding the length and 0x80.
  31.  
  32. -------------------------------------------------------------------------------
  33.  
  34. 1) Adding a new key to the index file:
  35.    Indexing/Reindexing a file:
  36.  
  37.     int IX_add (long            file_pos,
  38.                 char            *key_addr,
  39.                 unsigned char   data_type,
  40.                 int             file_handle);
  41.  
  42.     file_pos      - is the piece of data which will accompany the key.  This
  43.                     information will be returned to you when you use the
  44.                     IX_find_xxxxx function calls.  If you are working with
  45.                     fixed length records this can be a record length.  If you
  46.                     use this field to contain a record number, you will have
  47.                     to do multiplications to get it to a byte position within
  48.                     the file you are indexing.  You may simply use this field
  49.                     to contain the byte position of the record being indexed.
  50.     key_addr      - contains the address of either
  51.                     1) the key data
  52.                     2) a KEY_STRUCT (see INDEX.H) structure containing up to
  53.                        10 key parts.  The order of importance of the key
  54.                        fields is from lowest index to highest (i.e.
  55.                        KEY_COMPONENT.key[0] to KEY_COMPONENT.key[9]).
  56.     data_type     - specifies that the "key_value" above is either key data
  57.                     or a KEY_STRUCT structure (see INDEX.H).  If data_type
  58.                     designates key data, the length (in bytes) is also known.
  59.  
  60.     RETURNS:    One of the function returns shown in INDEX.H
  61.                     OK          where no errors were detected
  62.                     IX_IO_ERR
  63.                     IX_ERR
  64.                     INV_PARAM
  65.                     INV_NUM_KEYS
  66.  
  67.     EXAMPLE:    if we have a file with the following record layout which we
  68.                 wish to index on the last_name
  69.  
  70. -------------------------------------------------------------------------------
  71.     /* using the Microsoft "C" Optimizing compiler */
  72. #include <index.h>      /* after placing in include dir */
  73. #include <fcntl.h>
  74. #include <sys\types.h>
  75. #include <sys\stat.h>
  76. #include <io.h>
  77. #include <stdlib.h>
  78. #include <stdio.h>
  79.  
  80. #define TRUE        1
  81. #define FALSE       0
  82.  
  83. int nad_file;
  84. int index_file;
  85.  
  86. int num_bytes;
  87. int err;
  88. long file_pos = 0L;
  89.  
  90. struct {
  91.     char        first_name [15];
  92.     char        last_name [15];
  93.     char        addr [30];
  94.     char        city [20];
  95.     char        state [2];
  96.     char        zip [9];
  97. } name_and_addr;
  98.  
  99. main ()
  100. {
  101.     if ((nad_file = open ("nameaddr.fil", O_CREAT | O_BINARY | O_RDWR,
  102.                           S_IREAD | S_IWRITE)) == -1)
  103.     {
  104.        /* do something about the error */
  105.     }
  106.     if ((index_file = open ("nameaddr.inx", O_CREAT | O_BINARY | O_RDWR,
  107.                            S_IREAD | S_IWRITE)) == -1)
  108.     {
  109.       /* do something about the error */
  110.     }
  111.     while (TRUE)
  112.     {
  113.         num_bytes = read (nad_file, (char *)&name_and_addr,
  114.                           sizeof(name_and_addr));
  115.         if (num_bytes == 0)     /* end of file */
  116.             break;
  117.         if (num_bytes != sizeof(name_and_addr))
  118.         {
  119.            /* take care of short read */
  120.         }
  121.         err = IX_add (file_pos, name_and_addr.last_name,
  122.                       sizeof(name_and_addr.last_name)+0x80, index_file);
  123.                    /* 0x80 is simply the high order bit
  124.                       of the data_type.  For all other data
  125.                       types you can use the #define names
  126.                       (see INDEX.H) */
  127.         switch (err)
  128.         {
  129.             case OK:
  130.                 printf ("NAME: %15.15s indexed\n",
  131.                         name_and_addr.last_name);
  132.                 break;
  133.             case IX_IO_ERR:
  134.                 printf ("IO Error on \"nameaddr.inx\" file\n");
  135.                 break;
  136.             case IX_ERR:
  137.                 printf ("Index File is corrupted\n");
  138.                 break;
  139.             case INV_PARAM:
  140.                 printf ("Function Call Parameters don't match\n");
  141.                 printf (" information already in \"nameaddr.inx\"\n");
  142.                 break;
  143.             case INV_NUM_KEYS:
  144.                 printf ("The number of key fields does not match\n");
  145.                 printf (" information already in \"nameaddr.inx\"\n");
  146.                 break;
  147.             default: break;
  148.         }
  149.         if (err)
  150.             break;
  151.         file_pos += sizeof(name_and_addr);
  152.     }
  153. }
  154. -------------------------------------------------------------------------------
  155.  
  156. 2) Deleting an index entry from an index file:
  157.  
  158.     int IX_del (char            *key_addr,
  159.                 long            file_pos,
  160.                 unsigned char   data_type,
  161.                 int             file_handle);
  162.  
  163.     key_addr      - contains the address of either
  164.                     1) the key data
  165.                     2) a KEY_STRUCT (see INDEX.H) structure containing up to
  166.                        10 key parts.  The order of importance of the key
  167.                        fields is from lowest index to highest (i.e.
  168.                        KEY_COMPONENT.key[0] to KEY_COMPONENT.key[9]).
  169.     file_pos      - is the piece of data which will accompany the key.  This
  170.                     information will be returned to you when you use the
  171.                     IX_find_xxxxx function calls.  If you are working with
  172.                     fixed length records this can be a record length.  If you
  173.                     use this field to contain a record number, you will have
  174.                     to do multiplications to get it to a byte position within
  175.                     the file you are indexing.  You may simply use this field
  176.                     to contain the byte position of the record being indexed.
  177.                     The file position field is required in the delete to
  178.                     differentiate between duplicate keys and must be the same
  179.                     as used during IX_add.
  180.     data_type     - specifies that the "key_value" above is either key data
  181.                     or a KEY_STRUCT structure (see INDEX.H).  If data_type
  182.                     designates key data, the length (in bytes) is also known.
  183.  
  184.     RETURNS:    One of the function returns shown in INDEX.H
  185.                     OK          where no errors were detected
  186.                     IX_IO_ERR
  187.                     IX_ERR
  188.                     INV_PARAM
  189.                     INV_NUM_KEYS
  190.  
  191.     EXAMPLE:    if we have a file with the following record layout which we
  192.                 wish to de